home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: MegaDisc / MegaDisc 24 (1991-10)(MegaDisc Digital Publishing)(AU)(Disk 2 of 2).zip / MegaDisc 24 (1991-10)(MegaDisc Digital Publishing)(AU)(Disk 2 of 2).adf / PROGRAMS_B / AddMenu_doc / AddMenu_doc
Text File  |  1991-10-07  |  24KB  |  546 lines
  1.  
  2.  
  3.  
  4.         AddMenu V1.56 (25th Sep 1991) by Nic Wilson
  5.         -------------------------------------------
  6.  
  7.         Written totally in Assembler
  8.         ----------------------------
  9.         using Hisoft Devpac Amiga
  10.         -------------------------
  11.         on an Amiga A3000 25mhz
  12.         -----------------------
  13.  
  14.         Nic Wilson Software
  15.         138d South Street
  16.         Toowoomba Qld 4350
  17.         Australia
  18.         Ph (076) 358384 Work or FAX
  19.            (076) 358539 After hours
  20.  
  21.         EMAIL {cbmvax|cbmehq}!cbmaus!wilson!nic@uunet.uu.net
  22.  
  23.         This Version has been placed on Shareware for your enjoyment.
  24.         You may distribute it freely as long as this document and the
  25.         program remains unmodified, and accompanies the program.
  26.         You may modify the script files as examples as long as you
  27.         FULLY test them before distribution.
  28.  
  29.         **************************************************************
  30.  
  31.         THIS VERSION IS ONLY A TASTE OF WHAT IT TO COME.  VERSION 2.00
  32.         IS NEARING COMPLETION AND HAS EVEN MORE POWER.  IT ALLOWS ICON
  33.         ITEMS ON SCREEN THAT CAN BE COMPLETELY CHANGED EACH TIME A NEW
  34.         SCRIPT IS LAUNCHED.  THIS GIVES IT MUCH MORE POWER THAN OTHER
  35.         SIMILAR PROGRAMS AROUND.  ADDMENU V2.00 WILL BE A
  36.         COMMERCIAL PROGRAM BUT THE ASKING PRICE IS VERY REASONLBLE
  37.         AT $39.95 AND THIS ALSO GIVES YOU FREE UPDATES AND THERE ARE
  38.         OTHER UTILITIES ON THE DISK!!
  39.  
  40.         SEND FOR YOUR VERSION TODAY AND YOU WILL BE FIRST IN LINE
  41.         WHEN THE VERSION IS COMPLETE.  IT SHOULD BE READY BY THE
  42.         TIME YOU READ THIS.
  43.  
  44.         **************************************************************
  45.  
  46.         For the impatient:
  47.  
  48. QUICK SET UP
  49. ************
  50.  
  51.         O.K. you've just got a hold of AddMenu and you're dying to try
  52.         it out, but cannot be bothered reading the whole doc.
  53.  
  54.         Follow these few steps and you're away.
  55.  
  56.         launch the program with no option  EG.  AddMenu
  57.  
  58.         go to WorkBench and dump a few program icons over the AddMenu
  59.         icon that appeared on the Workbench window when you launched it.
  60.  
  61.         Now check out the Tools Menu you will find the programs there.
  62.  
  63.         Double-click the AddMenu icon and a window will open.
  64.  
  65.         Select the gadget that says 'Save Temporary Items to current Script'
  66.  
  67.         Because there isn't a current script a file requester will open
  68.         and prompt you for one.  Preferably give addmenu.script as the
  69.         filename, because this is AddMenu's default name it will always
  70.         load if you do not give it one.  Give subsequent script a name
  71.         that starts with addmenu.
  72.  
  73.         After you click the save gadget, a script file will be saved
  74.         that contains the items you placed there.
  75.  
  76.         Place the addmenu in your 'user-startup' file toward the bottom
  77.         preferably.
  78.  
  79.         Have a play with it or read the main docs now, for usage on all
  80.         the other options.
  81.  
  82.  
  83.         I hope you enjoy it!!
  84.  
  85.         Nic Wilson
  86.  
  87.  
  88.     ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ##
  89.  
  90.     The full docs continue here:
  91.  
  92.  
  93.         FUNCTION
  94.         --------
  95.         Add an infinite number of Menu Items to the Workbench Tools
  96.         Menu in Kickstart V2.0 using script files.  Updating is
  97.         possible from the menus, from CLI or from Workbench using
  98.         different script files.  Temporary menu items can also be
  99.         added that stay in the menu strip after updating to the new script,
  100.         and can also be converted to permanent and saved to your script
  101.         file automatically.
  102.  
  103.         REQUIREMENTS
  104.         ------------
  105.         Any Amiga running V2.0 of Kickstart and Workbench including
  106.         the A3000. Tested to versions 37.175 Kickstart and Workbench 37.66.
  107.  
  108.         HISTORY (Recent first)
  109.         ----------------------
  110.  
  111.         V1.56   Changed all the functions in the update window so they
  112.                 return to the update window when their job is complete.
  113.                 This I thought was better then exiting the update window.
  114.                 Checked the program thouroughly with Enforcer (see Autocli
  115.                 doc for more about Enforcer).
  116.  
  117.         V1.55   Added a new -s switch and completely changed the update
  118.                 window, to add the ability to save temporary menu items
  119.                 as permanent to the current script.  See -s option.
  120.  
  121.                 Added a 'MAKE NEW SCRIPT' gadget to the update window. See
  122.                 'MAKING A NEW SCRIPT FILE AUTOMATICALLY' for more info.
  123.  
  124.                 Removed the string gadget in the update window and
  125.                 replaced it with a gadget that opens the asl.library file
  126.                 requester.  It defaults to S: where I expect most users
  127.                 would keep their script files, and it defaults to matching
  128.                 files with the pattern add#?.
  129.  
  130.                 Added a 'Delete item from current script' function.  See
  131.                 'DELETING AN ITEM FROM THE CURRENT SCRIPT' for more info.
  132.  
  133.                 Added a 'Reposition' function. This allows any items within
  134.                 the current script to be repositioned in any order.  See
  135.                 'REPOSITIONING ITEMS WITHIN THE CURRENT SCRIPT' for more info.
  136.  
  137.                 Fixed a bug that must have been in for a while.  AddMenu would
  138.                 not launch with a script other than the default one.  This is
  139.                 now fixed.
  140.  
  141.                 AddMenu can now be launched without any script files at
  142.                 all and be configured completely by the update window and
  143.                 dumping icons over its icon.
  144.  
  145.                 AddMenu now hangs around a while if Workbench is busy on
  146.                 launch, and retries a few times before exiting.
  147.  
  148.         V1.54   Removed ability to run from Workbench because of severe
  149.                 problems in DOS being able to find things.  Run it from the
  150.                 user-startup and it is much better.
  151.  
  152.         V1.53   Changed launch code so the program can be called before
  153.                 Workbench is available.  This allows the program to be called
  154.                 from the user-startup instead of the startup-sequence.  The
  155.                 program will detach itself and then hang around and wait
  156.                 until workbench is available before installing.  Also changed
  157.                 it so it can be launched from Workbench and gave it a commodity
  158.                 icon.  You can drag this into the WBSTARTUP drawer to launch
  159.                 it if you prefer.  If you do it this way the default script
  160.                 MUST be s:addmenu.script as WB parameters are not supported
  161.                 yet.
  162.  
  163.         V1.52   Very sorry but the new about function didn't work in hi-res.
  164.                 I only use interlace and I negelected to test other resolution
  165.                 modes.  It is now fixed.
  166.  
  167.         V1.51   Added an 'About' menu automatically, this allows for easy
  168.                 identification of version number, author and info on its
  169.                 free distribution permission.  The 'About' menu will always
  170.                 be at the top of any function you have added in your script.
  171.  
  172.         V1.50   Fixed bug.  When updating to new script, old script memory
  173.                 buffers were not being freed.
  174.                 Added ability for each menu item to have more than one
  175.                 executable(See 'COMMAND STRINGS' or 'EXAMPLE SCRIPT' BELOW).
  176.  
  177.         V1.41   Stopped illegal devices, drawers or non-executables
  178.                 being added to the menu strip.  These will cause
  179.                 workbench screen to flash.
  180.                 Added switch for temporary menus, so you do not have
  181.                 to have the icon around if you do not use them.
  182.                 Added the ability to remove the temporary menus alone.
  183.         V1.42   Fixed bug.  If Temporary menus were removed, they would
  184.                 magically reappear when a script was changed.
  185.  
  186.         V1.40   New temporary menus via workbench icon added
  187.                 and ability to update or remove from this icon.
  188.         V1.31   Optimised and fixed error msg for illegal use
  189.                 under kickstart V1.3.
  190.                 Fully checked with 'Enforcer' for bugs.
  191.  
  192.         V1.3    Added ability to change scripts on update.
  193.  
  194.         V1.2    Added quit and update options.
  195.  
  196.         V1.1    Added ability to use different script name/path.
  197.  
  198.         V1.0    Original release.
  199.  
  200.         IMPORTANT
  201.          ---------
  202.          DO NOT USE RUN OR RUNBACK, ADDMENU WILL RETURN THE CLI
  203.          TO YOU AND ALLOW IT TO CLOSE WHEN YOU GIVE AN ENDCLI.
  204.  
  205.          ADDMENU WORKS IN RATHER A SPECIAL WAY, IN ORDER TO ALLOW THE
  206.          CLI WINDOW TO CLOSE AFTER LAUNCH IT RELAUNCHES ITSELF AGAIN
  207.          WITH SPECIAL CODE, THIS IS DONE TO OVERCOME ALL THE NORMAL PROBLEMS
  208.          ASSOCIATED WITH THIS.
  209.          YOU WILL NOTICE THAT SOME PROGRAMS LOSE THE PATH, STACK,
  210.          CURRENT DIRECTORY ETC. THIS IS ESPECIALLY TRUE OF PROGRAMS
  211.          WRITTEN IN C.  ADDMENU DOES NOT SUFFER FROM ANY OF THESE
  212.          PROBLEMS.  POPCLI TYPE PROGRAMS SUFFER BADLY FROM THIS, MY
  213.          AUTOCLI USES THIS SAME CODE AND SUFFERS NO PROBLEM.  IT IS
  214.          PUBLIC DOMAIN SO SEND S.S.A.E. AND DISK FOR THE LATEST VERSION.
  215.  
  216. USAGE
  217. *****
  218.          AddMenu [script] [switch]
  219.  
  220.          Standard redirection of output is supported.
  221.          EG. Addmenu >nil: [script]  [switch]
  222.  
  223. [switches]
  224.  
  225.   -s     AddMenu must already be running for this switch to be used.
  226.          is used to inform the running version that you wish to convert
  227.          any current temporary menu items in the current menu strip to
  228.          permanent and save them to the current script.  This allows you
  229.          to add items to each script file without having to manually
  230.          edit the script yourself.  This can also be done from the update
  231.          window accessed from AddMenu's special icon.
  232.  
  233.   -q     AddMenu must already be running for this switch to be used.
  234.          This switch allows the currently running AddMenu to be removed.
  235.          If AddMenu is not found running an error message will result.
  236.          If this switch is used then it must be the only parameter.
  237.          To remove from workbench see 'To Remove Addmenu Completely'
  238.          below.
  239.  
  240.   -t     Do not use temporary menus and do not place the icon on the
  241.          Workbench screen.
  242.  
  243. [script]
  244.          This is an optional parameter, and can be used when AddMenu is
  245.          first launched or when updating.  By default it reads a script
  246.          created by you, called 'addmenu.script'.  This file is expected
  247.          to be in the S: directory , but if you wish to supply a
  248.          different path and name you can use the script parameter.  If
  249.          this parameter is used you must supply the path to the file and
  250.          its name.  There is an example file that accompanies this file
  251.          to show you how to create it.  Below is an explanation of the
  252.          script file.
  253.  
  254.          EG. AddMenu DH0:s/addmenu.myscript
  255.  
  256.              or
  257.  
  258.              AddMenu s:addmenu.myscript
  259.  
  260. FROM Workbench
  261. --------------
  262.          This ability has been removed.
  263.  
  264. TEMPORARY MENU ITEMS
  265. ********************
  266.  
  267.          This function will default to ON unless the -t switch was
  268.          used at launch. AddMenu will place a special icon on the
  269.          workbench window.  If a program is dragged and dumped over
  270.          this icon, that program will appear at the bottom of the
  271.          menu strip.  The program itself will not move at all and
  272.          doing this is quite safe. These temporary menus will survive
  273.          an update that changes to a different script.  They will
  274.          continue to appear on the bottom of whatever script you
  275.          update with. Once added they can be removed without removing
  276.          AddMenu completely by double clicking on the special icon and
  277.          selecting the 'Remove Temporary Menu Items' gadget from the
  278.          window.   If any illegal device or non-executable file is
  279.          dumped over the icon the screen will flash and a beep sound
  280.          will be heard, and it will not be added to the menu.
  281.          These temporary menu items can be converted to permanent and
  282.          saved to the current script by choosing the 'Save Temporary...'
  283.          gadget from the update window or by launching AddMenu again
  284.          with the -s option.
  285.  
  286. ADDMENU's SPECIAL ICON
  287. **********************
  288.  
  289.          This icon does not behave like a normal icon, it is a special
  290.          icon that allows manipulation of AddMenu from the workbench.
  291.          Double clicking the icon will open a window with some gadgets.
  292.          These gadgets allow AddMenu to be removed, temporary menus
  293.          removed, updating a script or to cancel the operation etc.  They
  294.          are all explained in the relative sections below.  This icon
  295.          has not been given any specific position on the workbench window.
  296.          Workbench will choose the best position for the icon, it can
  297.          of course be dragged to any place you wish.
  298.  
  299. CANCELLING THE WINDOW
  300. *********************
  301.          If you double clicked the special icon, the window opened, and
  302.          you changed your mind and wish to exit without changes.  Click
  303.          the 'CANCEL' gadget or the CLOSE gadget on the window.  This will
  304.          abort the operation and AddMenu will be unchanged.
  305.  
  306. SAVING TEMPORARY MENU ITEMS TO THE CURRENT SCRIPT FILE
  307. ******************************************************
  308.  
  309. From CLI
  310. -------- Launch AddMenu again with the -s switch.  This will tell AddMenu
  311.          to convert the current temporary menu items to permanent and
  312.          save them to the current script file.  After this is done the
  313.          menus will be updated to reflect the temporaries as permanent.
  314.          This save option can save one or more temporary menu items
  315.          in one go.  You could also place 'AddMenu -s' into each script
  316.          file you use so it can be chosen from each menu, instead of the
  317.          CLI or update window.
  318.  
  319. From Workbench
  320. --------------
  321.          Double click the special AddMenu icon that appeared on the
  322.          workbench window when AddMenu was launched.  A window will
  323.          open.  Click the 'Save Temporary Menu Items to Current Script'
  324.          gadget.  If no temporary menus are found then this gadget will
  325.          be ghosted.
  326.  
  327. TO REMOVE THE TEMPORARY MENUS
  328. *****************************
  329. From CLI
  330. --------
  331.          Not possible.
  332.  
  333. From Workbench only
  334. -------------------
  335.          Double click the special icon that appeared on the Workbench
  336.          window when AddMenu was launched.  Click the 'Remove Temporary..'
  337.          Gadget.  All temporary menus will be removed.  They cannot be
  338.          removed individually unless you convert them to permanent with
  339.          the 'Save Temp..' gadget and then the 'Delete Item..' to delete
  340.          specific ones.
  341.          If there are no temporary menus then the gadgets will be ghosted.
  342.  
  343. DELETING AN ITEM FROM THE CURRENT SCRIPT
  344. ****************************************
  345.  
  346. From CLI
  347. -------- The only way from CLI is to edit the script manually with an
  348.          editor.
  349.  
  350. From Workbench
  351. --------------
  352.          Double click on the AddMenu icon and a window will open.  Click
  353.          on the 'Delete item from current script' gadget and another window
  354.          will open, this window will show all the items in the current
  355.          script.  Each item is a toggle select gadget.  Choose one or
  356.          more entries to delete and when finished click the 'DELETE' gadget
  357.          and they are gone.  You may abort this function with the 'CANCEL'
  358.          gadget.
  359.  
  360. REPOSITIONING ITEMS WITHIN THE CURRENT SCRIPT
  361. *********************************************
  362.  
  363. From CLI
  364. -------- The only way from CLI is to edit the script manually with an
  365.          editor.
  366.  
  367. From Workbench
  368. --------------
  369.          Double click on the AddMenu icon and a window will open.  Click
  370.          on the 'Reposition an Entry in Current Script' gadget and another
  371.          window will open, this window will show all the items in the
  372.          current script.  Each item is a toggle select gadget.  Choose two
  373.          entries to swap place and they will swap.  Keep doing this until
  374.          all entries are in the position you desire them to be. When
  375.          finished click the 'SAVE' gadget and your script file and the menu
  376.          strip will be updated to reflect these changes.  You may abort
  377.          this function with the 'CANCEL' gadget.
  378.  
  379. UPDATING ADDMENU ONCE RUNNING
  380. *****************************
  381. From CLI
  382. --------
  383.          If AddMenu is already installed when launched again, then it will
  384.          send a message to the running version to update itself,  If no
  385.          script is supplied then it will update from the default file.
  386.          A different script can be supplied as the update, and because this
  387.          update can be called from inside an AddMenu script, this allows
  388.          you to change the entire menu, by calling a menu function.
  389.          This allows for an infinite number of available menu functions.
  390.          If a different script is supplied to the current one then it will
  391.          be totally replaced in favour of the new script.  This new script
  392.          could of course have an option to return to the original or any
  393.          number of other scripts.
  394.  
  395. From Workbench
  396. --------------
  397.          Double click the special AddMenu icon that appeared on the
  398.          workbench window when AddMenu was launched.  A window will
  399.          open.  Click the 'Change Tools Menu to different Script' gadget,
  400.          and a file requester will appear.  This file requester has a
  401.          pattern matching string gadget that will default to showing
  402.          all files that begin with 'add'.  I suggest that you call your
  403.          scripts addmenu.????? to take advantage of this, otherwise you
  404.          may click in the 'Pattern' gadget and change the display pattern.
  405.          Select your new script file, then the  menus will be updated if
  406.          your new script was valid.
  407.  
  408. TO REMOVE ADDMENU COMPLETELY
  409. ****************************
  410. From CLI
  411. --------
  412.          Launch AddMenu again with the -q switch. (SEE Usage Above)
  413.          This could also be done by placing an entry in your script
  414.          file so quitting could be done from the menus.
  415.  
  416. From Workbench
  417. --------------
  418.          Double click the special icon that appeared on the Workbench
  419.          window when AddMenu was launched.  Click the 'Quit Addmenu'
  420.          Gadget.  AddMenu will be completely removed.
  421.  
  422. THE SCRIPT FILE
  423. ***************
  424.          The maximum number of items allowed in each menu script
  425.          is 63.  This is not a limitation of AddMenu, but a limitation
  426.          that Workbench has placed for the tools menu.  I do not
  427.          recommend using that many anyway, as they would be too
  428.          cluttered.  Use less per menu and make more scripts.
  429.  
  430. MAKING A NEW SCRIPT FILE AUTOMATICALLY
  431. **************************************
  432.          AddMenu can make a new script file for you automatically if
  433.          you wish.  To do this select 'MAKE NEW SCRIPT...' from the menu
  434.          and a file requester will open and prompt you for a new file
  435.          name for the script.  The S: directory will be the default
  436.          directory that the file requester will open in and the default
  437.          pattern matching will be add#?,  you may change this if
  438.          desired. Type a new file name or select an old one to overwrite
  439.          and click on the LOAD gadget.  This new empty file will be
  440.          created on the disk, and the menus will be removed, with only
  441.          the 'ABOUT ADDMENU' and MAKE NEW SCRIPT...' items available.
  442.          Drag programs you wish to place in this new script and dump
  443.          them over the AddMenu Icon.  If the program you want to place
  444.          in there does not have an icon, then select the 'All Files'
  445.          sub-item from the 'Show' item of the Window menu of the workbench
  446.          window.  This will give all files and drawers a fake icon in the
  447.          current window,  keep doing this until you get to your file.
  448.          After you have placed all required files in the new menu,
  449.          double-click on the AddMenu icon and select 'Save Temporary Menu
  450.          Items to Current Script'.  The new script will be updated and
  451.          will now be available.
  452.  
  453. MAKING A NEW SCRIPT FILE MANUALLY
  454. *********************************
  455.          The script file is a group of commands you would like in the
  456.          menu along with the text you want in the actual menu.
  457.          The format of this script is important for the program to read
  458.          it correctly.  If the number of menu items in a single script
  459.          overflows the screen height,  the menu strips will be made
  460.          wider and the items split into columns.  The maximum number
  461.          of menus items in a single script is 63, but due to a bug
  462.          in workbench.library this is not checked for, any extra menus
  463.          over this amount will be clipped, athough I dont forsee anyone
  464.          placing this many in a single script.  The structure of the
  465.          script file is as follows.
  466.  
  467. TEXT STRINGS
  468. ++++++++++++
  469.          The text strings are actually placed in the menu, and each one
  470.          must be before its command string.  The Text string MUST START
  471.          and END with a plus (+) sign.
  472.  
  473. COMMAND STRINGS
  474. ***************
  475.          The command strings are the strings that are sent to DOS when
  476.          a menu item is selected.  Each one MUST come directly after
  477.          its text string and START and END with an asterisk (*).  There
  478.          are now any number of commands allowed per text string,
  479.          DO NOT USE THE 'RUN' COMMAND WITHIN A COMMAND STRING,  'RUN'
  480.          WILL BE ADDED TO THE FRONT OF YOUR STRING AUTOMATICALLY.
  481.  
  482. END OF FILE MARKER (IMPORTANT!!)
  483. ################################
  484.  
  485.          The script file MUST END with a hash (#) sign on the beginning
  486.          of a new line.
  487.  
  488. COMMENTS
  489. ;;;;;;;;
  490.          Comments are allowed in the script file but must follow certain
  491.          guidelines.  They are allowed on a line of their own or beside
  492.          a text string or command string. They must be outside the command
  493.          or text string characters.  The best way to ensure this is to
  494.          leave at least one space before the beginning of the comment after
  495.          the rightmost plus (+) or asterisk (*) of each comment or text
  496.          string.  They MUST NOT use the plus (+) sign, the asterisk (*)
  497.          or the hash (#) sign within the comment, as these three
  498.          characters are used to specify the beginning and end of command,
  499.          texts strings or end of file.  Comment lines are completely
  500.          optional, you do not have to have any at all.
  501.  
  502. EXAMPLE OF A VALID SCRIPT
  503. -------------------------
  504. ;this is a valid comment
  505. this is a valid comment
  506.     this is still a valid comment
  507. +NEWSHELL+                      ;Text for the menu surrounded in plus signs
  508. *c:newshell*                    ;commands surrounded in asterisk signs
  509.                                 comments are allowed between menu strings
  510. +NoVirus+                       this is still a valid comment
  511. *dh0:novirus*                   notice the path to the above command
  512. +WordPerfect+
  513. *assign WP: dh0:wp*             an example of multiple commands
  514. *assign PRINT: dh0:wp*          with a menu entry.
  515. *assign SPELL.THES: dh0:wp*
  516. *cd wp:*
  517. *wp*
  518. +XCOPY+                         to assign and run it
  519. *dh0:copiers/xcopy*
  520. +Quit Addmenu+
  521. *addMenu -q*                    ;how to make AddMenu quit from the menus
  522.  
  523. +Another Menu+                  ;how to change menus from a menu
  524. *addmenu s:different.script*    ;(updating AddMenu)
  525. #
  526.          Notice the 'end of file' marker (#) on the end of the script.
  527.          This is very important.
  528.  
  529.  
  530.          Please send comments, bug reports etc to the address at the
  531.          top of this file.
  532.  
  533.          Nic Wilson
  534.  
  535.  
  536.  
  537.  
  538.     ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ## 24 ##
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.